package org.marketlive.entity;

/*
(C) Copyright MarketLive. 2006. All rights reserved.
MarketLive is a trademark of MarketLive, Inc.
Warning: This computer program is protected by copyright law and international treaties.
Unauthorized reproduction or distribution of this program, or any portion of it, may result
in severe civil and criminal penalties, and will be prosecuted to the maximum extent
possible under the law.
*/


import java.util.Date;
import java.util.Locale;
import java.util.Map;
import java.util.List;

/**
 * Represents data that has a unique identity and a persists across more than one process.
 * The unique identity is a primary key.
 */
public interface IEntity extends IMMLHibernate {


    /**
     * Returns the unique identity of this <code>IEntity</code>.
     * The returned key is null if this <code>IEntity</code> has not been persisted yet.
     *
     * @return the <code>IPrimaryKey</code> of this <code>IEntity</code>
     */
    IPrimaryKey getPk();

    /**
     * Returns the version of this <code>IEntity</code>.
     * Versions can be used to implement caching. Implementations that do not
     * implement caching should return 0 (zero).
     *
     * @return the version of this <code>IEntity</code>
     */
    int getVersion();

    /**
     * Sets the version of this <code>IEntity</code>.
     * Versions can be used to implement caching. Implementations that do not
     * implement caching should indicate to the caller that this operation
     * is meaningless in those implementations.
     *
     * @param version the version
     */
    void setVersion(int version);

    /**
     * Returns the merchant's unique identifier for this <code>IEntity</code>.
     * Typically, <code>code</code> is the entity's primary key in the merchant's
     * system of record.
     *
     * @return the merchant's unique identifier for this <code>IEntity</code>
     */
    String getCode();

    /**
     * Sets the merchant's unique identifier for this <code>IEntity</code>.
     * Typically, <code>code</code> is the entity's primary key in the merchant's
     * system of record. In implementations that support integrating with the
     * merchant's backend systems, <code>code</code> cannot be null.
     *
     * @param code the merchant's unique identifier for this <code>IEntity</code>
     */
    void setCode(String code);

    /**
     * Returns the <code>Date</code> this <code>IEntity</code> was created.
     * The date cannot be null.
     *
     * @return when this <code>IEntity</code> was created
     */
    Date getDateCreated();

    /**
     * Sets the <code>Date</code> this <code>IEntity</code> was created.
     * The date cannot be null.
     *
     * @param dateCreated when this <code>IEntity</code> was created
     */
    void setDateCreated(Date dateCreated);

    /**
     * Returns the <code>Date</code> this <code>IEntity</code> was last modified.
     *
     * @return when this <code>IEntity</code> was last modified
     */
    Date getDateModified();

    /**
     * Sets the <code>Date</code> this <code>IEntity</code> was last modified.
     *
     * @param dateModified when this <code>IEntity</code> was last modified
     */
    void setDateModified(Date dateModified);

    /**
     * Returns the <code>IAttributePage</code> with the given name and locale.
     * Searches both localized and non-localized page collections.
     * If no such page exists, creates a new one.
     *
     * @param pageName name of the page to retrieve or create
     * @param locale the locale of the page to retrieve or create
     * @return an <code>IAttributePage</code> with the given name
     */
    IAttributePage getPage(String pageName, Locale locale);
    
    /**
     * Returns a read-only Map of localized <code>IAttributePage</code>s keyed by
     * locale string (e.g. en_US).
     * @param pageName type of <code>IAttributePage</code> to return in <code>Map</code> value.
     * @return <code>Map</code> of attribute pages of the given type for all locales, keyed on locale.
     */
    Map<String, IAttributePage> getAttributePageForAllLocales(String pageName);
    
    /**
     * Returns a read-only collection of <code>IAttributePage</code>s contained in this entity.
     * The attribute pages themselves may be modified; however, the changes to the returned collection,
     * such as adding to or removing from it, are not persisted. To add a page to this entity,
     * follow the form
     * <pre>
     * IAttributePage newPage = entity.getPage("newPageName");
     * // set values on newPage as needed...
     * entity.setPage("newPageName", newPage);
     * </pre>
     *
     * @return a <code>Map</code> of attribute pages, keyed on page name
     */
    public Map<String, IAttributePage> getPages();

    /**
     * Returns the home for this <code>IEntity</code>.
     * The home cannot be null.
     *
     * @return the <code>IEntityHome</code> for this <code>IEntity</code>
     */
    IEntityHome getEntityHome();

    /**
     * Returns this entity's type.
     *
     * @return the type of this <code>IEntity</code>
     */
    String getEntityType();

    /**
     * Compares the given object with this one, using primary key to determine equality.
     *
     * @param o the <code>Object</code> to compare to this <code>IEntity</code>
     * @return true if <code>o</code> has an <code>IPrimaryKey</code> equal to the key of this <code>IEntity</code>
     */
    boolean equals(Object o);
}
